home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / catn / scrollbar.n < prev    next >
Text File  |  1994-09-20  |  10KB  |  265 lines
  1.  
  2.  
  3.  
  4. scrollbar(n)               Tk Commands
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      scrollbar - Create and manipulate scrollbar widgets
  12.  
  13. SYNOPSIS
  14.      scrollbar _p_a_t_h_N_a_m_e ?_o_p_t_i_o_n_s?
  15.  
  16. STANDARD OPTIONS
  17.      activeForeground               cursor          relief         |
  18.      background      foreground     repeatDelay
  19.      borderWidth     orient         repeatInterval
  20.  
  21.      See the ``options'' manual entry for details on the standard
  22.      options.
  23.  
  24. WIDGET-SPECIFIC OPTIONS
  25.      Name:           command
  26.      Class:          Command
  27.      Command-Line Switch:-command
  28.  
  29.           Specifies the prefix of a  Tcl  command  to  invoke  to
  30.           change  the  view  in  the  widget  associated with the
  31.           scrollbar.  When a user requests a view change by mani-
  32.           pulating  the scrollbar, a Tcl command is invoked.  The
  33.           actual command consists of this option  followed  by  a
  34.           space  and  a number.  The number indicates the logical
  35.           unit that should appear at the top  of  the  associated
  36.           window.
  37.  
  38.      Name:           width
  39.      Class:          Width
  40.      Command-Line Switch:-width
  41.  
  42.           Specifies the desired narrow dimension of the scrollbar
  43.           window, not including 3-D border, if any.  For vertical
  44.           scrollbars this will be the width  and  for  horizontal
  45.           scrollbars this will be the height.  The value may have  |
  46.           any of the forms acceptable to Tk_GetPixels.
  47. _________________________________________________________________
  48.  
  49.  
  50. DESCRIPTION
  51.      The scrollbar command creates a new  window  (given  by  the
  52.      _p_a_t_h_N_a_m_e  argument)  and  makes  it into a scrollbar widget.
  53.      Additional options, described above, may be specified on the
  54.      command  line or in the option database to configure aspects
  55.      of the  scrollbar  such  as  its  colors,  orientation,  and
  56.      relief.   The  scrollbar  command returns its _p_a_t_h_N_a_m_e argu-
  57.      ment.  At the time this command is invoked, there  must  not
  58.      exist  a  window  named _p_a_t_h_N_a_m_e, but _p_a_t_h_N_a_m_e's parent must
  59.      exist.
  60.  
  61.  
  62.  
  63. Tk                                                              1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. scrollbar(n)               Tk Commands
  71.  
  72.  
  73.  
  74.      A scrollbar is a widget that displays  two  arrows,  one  at
  75.      each  end  of the scrollbar, and a _s_l_i_d_e_r in the middle por-
  76.      tion of the scrollbar.   A  scrollbar  is  used  to  provide
  77.      information  about  what  is visible in an _a_s_s_o_c_i_a_t_e_d _w_i_n_d_o_w
  78.      that displays an object of some sort (such as a  file  being
  79.      edited  or  a drawing).  The position and size of the slider
  80.      indicate which portion of the object is visible in the asso-
  81.      ciated  window.   For  example,  if the slider in a vertical
  82.      scrollbar covers the top third of the area between  the  two
  83.      arrows, it means that the associated window displays the top
  84.      third of its object.
  85.  
  86.      Scrollbars can be used to adjust the view in the  associated
  87.      window  by  clicking  or  dragging  with the mouse.  See the
  88.      BINDINGS section below for details.
  89.  
  90.  
  91. WIDGET COMMAND
  92.      The scrollbar command creates a new Tcl command  whose  name
  93.      is  _p_a_t_h_N_a_m_e.   This  command  may be used to invoke various
  94.      operations on the widget.   It  has  the  following  general
  95.      form:
  96.  
  97.           _p_a_t_h_N_a_m_e _o_p_t_i_o_n ?_a_r_g _a_r_g ...?
  98.  
  99.      _O_p_t_i_o_n and the _a_r_gs determine the exact behavior of the com-
  100.      mand.   The  following  commands  are possible for scrollbar
  101.      widgets:
  102.  
  103.      _p_a_t_h_N_a_m_e configure ?_o_p_t_i_o_n? ?_v_a_l_u_e _o_p_t_i_o_n _v_a_l_u_e ...?
  104.           Query  or  modify  the  configuration  options  of  the
  105.           widget.   If  no  _o_p_t_i_o_n  is  specified, returns a list
  106.           describing all of the available  options  for  _p_a_t_h_N_a_m_e
  107.           (see  Tk_ConfigureInfo for information on the format of
  108.           this list).  If _o_p_t_i_o_n is specified with no _v_a_l_u_e, then
  109.           the  command  returns  a  list describing the one named
  110.           option (this list will be identical to the  correspond-
  111.           ing  sublist  of  the  value  returned  if no _o_p_t_i_o_n is
  112.           specified).  If one  or  more  _o_p_t_i_o_n-_v_a_l_u_e  pairs  are
  113.           specified,  then  the command modifies the given widget
  114.           option(s) to have the given value(s);  in this case the
  115.           command  returns  an empty string.  _O_p_t_i_o_n may have any
  116.           of the values accepted by the scrollbar command.
  117.  
  118.      _p_a_t_h_N_a_m_e get
  119.           Returns a Tcl  list  containing  four  decimal  values,
  120.           which  are  the  current  _t_o_t_a_l_U_n_i_t_s, _w_i_d_n_o_w_U_n_i_t_s, _f_i_r_-
  121.           _s_t_U_n_i_t, and _l_a_s_t_U_n_i_t values for the  scrollbar.   These
  122.           are  the values from the most recent set widget command
  123.           on the scrollbar.
  124.  
  125.      _p_a_t_h_N_a_m_e set _t_o_t_a_l_U_n_i_t_s _w_i_n_d_o_w_U_n_i_t_s _f_i_r_s_t_U_n_i_t _l_a_s_t_U_n_i_t
  126.           This  command  is  invoked  to   give   the   scrollbar
  127.  
  128.  
  129.  
  130. Tk                                                              2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. scrollbar(n)               Tk Commands
  137.  
  138.  
  139.  
  140.           information   about  the  widget  associated  with  the
  141.           scrollbar.  _T_o_t_a_l_U_n_i_t_s is an integer value  giving  the
  142.           total size of the object being displayed in the associ-
  143.           ated widget.  The meaning of one unit  depends  on  the
  144.           associated  widget;   for  example,  in  a  text editor
  145.           widget units might correspond to lines of  text.   _W_i_n_-
  146.           _d_o_w_U_n_i_t_s  indicates  the total number of units that can
  147.           fit in the associated window at  one  time.   _F_i_r_s_t_U_n_i_t
  148.           and  _l_a_s_t_U_n_i_t  give  the  indices of the first and last
  149.           units currently visible in the associated window  (zero
  150.           corresponds  to  the  first  unit of the object).  This
  151.           command should be  invoked  by  the  associated  widget
  152.           whenever its object or window changes size and whenever
  153.           it changes the view in its window.
  154.  
  155.  
  156. BINDINGS
  157.      The  description   below   assumes   a   vertically-oriented
  158.      scrollbar.   For  a  horizontally-oriented scrollbar replace
  159.      the words ``up'', ``down'',  ``top'',  and  ``bottom''  with
  160.      ``left'', ``right'', ``left'', and ``right'', respectively
  161.  
  162.      A scrollbar widget is  divided  into  five  distinct  areas.
  163.      From  top  to  bottom, they are:  the top arrow, the top gap
  164.      (the empty space between the  arrow  and  the  slider),  the
  165.      slider,  the  bottom  gap,  and  the bottom arrow.  Pressing
  166.      mouse button 1 in each area has a different effect:
  167.  
  168.      top arrow           Causes the view in the associated window
  169.                          to shift up by one unit (i.e. the object
  170.                          appears to move down  one  unit  in  its
  171.                          window).  If the button is held down the
  172.                          action will auto-repeat.
  173.  
  174.      top gap             Causes the view in the associated window
  175.                          to  shift up by one less than the number
  176.                          of units in the window (i.e. the portion
  177.                          of the object that used to appear at the
  178.                          very top of the window will  now  appear
  179.                          at  the  very bottom).  If the button is
  180.                          held down the action will auto-repeat.
  181.  
  182.      slider              Pressing button 1 in this  area  has  no
  183.                          immediate  effect  except  to  cause the
  184.                          slider  to  appear  sunken  rather  than
  185.                          raised.   However, if the mouse is moved
  186.                          with the button  down  then  the  slider
  187.                          will  be  dragged, adjusting the view as
  188.                          the mouse is moved.
  189.  
  190.      bottom gap          Causes the view in the associated window
  191.                          to  shift  down  by  one  less  than the
  192.  
  193.  
  194.  
  195. Tk                                                              3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. scrollbar(n)               Tk Commands
  203.  
  204.  
  205.  
  206.                          number of units in the window (i.e.  the
  207.                          portion  of  the  object  that  used  to
  208.                          appear at the very bottom of the  window
  209.                          will  now  appear  at the very top).  If
  210.                          the button is held down the action  will
  211.                          auto-repeat.
  212.  
  213.      bottom arrow        Causes the view in the associated window
  214.                          to  shift  down  by  one  unit (i.e. the
  215.                          object appears to move up  one  unit  in
  216.                          its window).  If the button is held down
  217.                          the action will auto-repeat.
  218.  
  219.      Note:  none of the actions described above has an  immediate
  220.      impact  on  the position of the slider in the scrollbar.  It
  221.      simply invokes the command specified in the  command  option
  222.      to  notify  the  associated  widget that a change in view is
  223.      desired.  If the view is actually changed then  the  associ-
  224.      ated  widget  must invoke the scrollbar's set widget command
  225.      to change what is displayed in the scrollbar.
  226.  
  227.  
  228. KEYWORDS
  229.      scrollbar, widget
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261. Tk                                                              4
  262.  
  263.  
  264.  
  265.